home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / cool / ge_cool.lha / GE_COOL2.1 / man / oldman3 / Queue.3T < prev    next >
Text File  |  1992-06-26  |  9KB  |  315 lines
  1. .TH QUEUE
  2. .SH NAME
  3. Queue<Type>\f1  A dynamic, parameterized queue
  4. .SH SYNOPSIS
  5. #include <cool/Queue.h>
  6. .SH  DESCRIPTION
  7. The \f3Queue<Type>\f1 class implements a conventional first-in, first-out data 
  8. structure that holds a user-specified data type. All memory management and 
  9. initialization is encapsulated and performed by the class constructors and 
  10. member functions. Queue objects can be either static-sized or dynamic. Queues 
  11. are, by default, dynamic in nature. A static-sized queue object is selected by 
  12. setting the growth allocation size to zero or by passing in a pointer to a 
  13. block of user-supplied storage to the constructor. If a queue is of static size 
  14. and an operation is performed that requires more storage, an 
  15.  \f3\f3Error\f1\f1 
  16. exception is 
  17. raised.
  18. .PP
  19. The \f3Queue<Type>\f1 class implements the notion of a current position. This is 
  20. useful for iterating through the elements of a queue. The current position is 
  21. maintained in a data member of type 
  22.  Queue_state 
  23. and is set or reset by all 
  24. member functions affecting elements in the class. Member functions are  
  25. provided to reset the current position, move to the next  and previous 
  26. elements, find an element, and get the value at the current position. The \f3Iterator<Type>\f1 class provides a mechanism to save and restore the state  
  27. associated with the current position, thus allowing the programmer to use 
  28. multiple iterators over the same instance of a queue.
  29. .PP
  30. The \f3Queue<Type>\f1 class allows the programmer to add and/or remove items from 
  31. either end of the queue. In addition, the current position and iterator 
  32. functions allow the programmer to examine other entries in the middle of the 
  33. queue and remove or change them. This would be useful in implementing a 
  34. prioritized queue where the entries may need to be rearranged at times.
  35. .SH Base Classes
  36.  Queue, 
  37. .SH Friend Classes
  38. None
  39. .SH Constructors
  40. .TP
  41. \f3Queue<Type> ();\f1
  42. Creates an empty queue of the specified type.
  43. .TP
  44. \f3Queue<Type> (unsigned long \f2number\f3);\f1
  45. Allocates enough storage for a queue of a specific type to hold 
  46.  number of 
  47. elements specified by the argument.
  48. .TP
  49. \f3Queue<Type> (const Queue<Type>& q\f3);\f1
  50. Duplicates the size and value of a queue object 
  51.  q . 
  52. .TP
  53. \f3Queue<Type> (void* \f2storage\f3, unsigned long \f2number\f3);\f1
  54. Creates a static-sized queue object for 
  55.  number 
  56. of elements whose storage 
  57.  storage 
  58. is provided by the user. If an object of this type attempts to grow 
  59. dynamically or the programmer invokes the 
  60.  resize 
  61. member function, an 
  62.  \f3\f3Error\f1\f1 
  63. exception is raised.
  64. .SH Member Functions
  65. .TP
  66.  inline long capacity () const;
  67. Returns the maximum number of elements the stack can contain.
  68. .TP 
  69.  void clear ();
  70. Sets the number of items in the queue to zero. This function invalidates the 
  71. current \p
  72. position.
  73.  
  74. .TP
  75.  inline Queue_state& current_position ();
  76. Returns a reference to the state information associated with the current 
  77. position. This function should be used with the \f3Iterator<Type>\f1 class to save 
  78. and restore the current position, thus facilitating multiple iterators over an 
  79. instance of queue.
  80. .TP
  81. \f3Boolean find (const Type& value\f3);\f1
  82. Searches the queue for 
  83.  value . 
  84. If 
  85.  value 
  86. is found, this function sets the current 
  87. position and returns 
  88.  
  89.  TRUE ; 
  90. otherwise, this function resets the current position 
  91. and returns 
  92.  
  93.  FALSE .
  94. .TP
  95.  Type& get ();
  96. Removes and returns a reference to the first-in item on the queue. If there are 
  97. no elements in the queue, an 
  98.  \f3\f3Error\f1\f1 
  99. exception is raised.
  100. .TP
  101.  inline Boolean is_empty () const;
  102. Returns 
  103.  
  104.  TRUE 
  105. if there are no items in the queue. Otherwise, this function 
  106. returns 
  107.  
  108.  FALSE .
  109. .TP
  110.  inline long length () const;
  111. Returns the number of elements in the queue.
  112. .TP
  113.  inline Type& look ();
  114. Returns the first-in item on the queue. If there are no elements in the queue, 
  115. an 
  116.  \f3\f3Error\f1\f1 
  117. exception is raised.
  118. .TP
  119.  Boolean next ();
  120. Advances the current position to the next element in the queue and returns 
  121.  
  122.  TRUE .  
  123. If the current position is invalid, this function sets the current 
  124. position to the first element and returns 
  125.  
  126.  TRUE .  
  127. If the current position is the 
  128. last element of the queue, this function invalidates the current position and 
  129. returns 
  130.  
  131.  FALSE .
  132. .TP
  133. \f3Queue<Type>& \f3operator= (const Queue<Type>& q\f3);\f1
  134. Overloads the assignment operator for the 
  135.  Queue 
  136. class and assigns 
  137.  q
  138. to the 
  139. queue object by duplicating the size and element values. This function 
  140. invalidates the current position.
  141. .TP
  142. \f3Boolean operator== (const Queue<Type>& q\f3) const;\f1
  143. Overloads the equality operator for the 
  144.  Queue 
  145. class. This function returns 
  146.  
  147.  TRUE 
  148. if the queues have an equal number of elements with the same values; otherwise, 
  149. this function returns 
  150.  
  151.  FALSE .
  152. .TP
  153. \f3inline Boolean operator!= (const Queue<Type>& q\f3) const;\f1
  154. Overloads the inequality operator for the 
  155.  Queue 
  156. class. This function returns 
  157.  
  158.  TRUE 
  159. if the queues have an unequal number of elements or unequal values.
  160. .TP
  161.  Boolean prev ();
  162. Moves the current position pointer to the previous element in the queue and 
  163. returns 
  164.  TRUE . 
  165. If the current position is invalid, this function moves to the 
  166. last element and returns 
  167.  
  168.  TRUE . 
  169. If the current position is the first element in 
  170. the queue, this function invalidates the current position and returns 
  171.  
  172.  FALSE .
  173. .TP
  174. \f3Boolean put (const Type& value\f3);\f1
  175. Puts 
  176.  value 
  177. onto the back of the queue, making it the last-in item. If required 
  178. and not prohibited, this function grows the queue, puts the new last-in item on 
  179. the queue, and returns 
  180.  
  181.  TRUE . 
  182. Otherwise, this function returns 
  183.  
  184.  FALSE .
  185. .TP
  186.  Boolean remove ();
  187. Removes the element at the current position. This function returns 
  188.  
  189.  FALSE 
  190. if the 
  191. current position is invalid; otherwise, this function sets the current position 
  192. to the element immediately following the element removed (if not at end of 
  193. queue) and returns 
  194.  
  195.  TRUE . 
  196. If the current position is at the last element before 
  197. removing, this function invalidates the current position and returns 
  198.  TRUE  
  199. after removing the element.
  200.  
  201. .TP
  202. \f3Boolean remove (const Type& value\f3);\f1
  203. Searches for 
  204.  value 
  205. and, if found, this function removes and sets the current 
  206. position to the element immediately following the element removed, and then it 
  207. returns 
  208.  
  209.  TRUE . 
  210. If 
  211.  value 
  212. is found but at the end of the queue, this function 
  213. invalidates the current position and returns 
  214.  
  215.  TRUE . 
  216. If the element is not found, 
  217. this function returns 
  218.  
  219.  FALSE .
  220. .TP
  221.  inline void reset ();
  222. Invalidates the current position.
  223. .TP
  224. \f3void resize (long \f2number\f3);\f1
  225. Resizes the queue for at least 
  226.  number 
  227. of elements. If a growth ratio has been 
  228. selected and it satisfies the resize request, the queue is grown by this ratio, 
  229. the current position is invalidated, and 
  230.  
  231.  TRUE 
  232. is returned. Otherwise, this 
  233. function returns 
  234.  
  235.  FALSE . 
  236. If the size specified is zero or negative, an 
  237.  \f3\f3Error\f1\f1 
  238. exception is raised.
  239. .TP
  240. \f3inline void set_alloc_size (int \f2size\f3);\f1
  241. Updates the allocation growth size to be used when the growth ratio is zero. 
  242. Default allocation growth size is 100 bytes. If the size specified is negative, 
  243. an 
  244.  \f3\f3Error\f1\f1 
  245. exception is raised.
  246. .TP
  247. \f3inline void set_compare (\f2Queue_Compare \f3= NULL);\f1
  248. Updates the compare function for this class of queue. 
  249.  Queue_Compare 
  250. is a 
  251. function of type 
  252.  Boolean 
  253. (\f2*Function\f1)(\f3const Type&\f1, \f3const Type&\f1). If no argument 
  254. is provided, the 
  255.  operator== 
  256. for the type over which the class is parameterized 
  257. is used.
  258. .TP
  259. \f3inline void set_growth_ratio (float \f2ratio\f3);\f1
  260. Updates the growth ratio for this instance of a queue to 
  261.  ratio . 
  262. When a queue 
  263. needs to grow, the current size is multiplied by the ratio to determine the new 
  264. size. If 
  265.  ratio 
  266. is negative, an 
  267.  \f3\f3Error\f1\f1 
  268. exception is raised.
  269. .TP
  270. \f3Boolean unget (const Type& value\f3);\f1
  271. Puts 
  272.  value 
  273. onto the front of the queue. If required and not prohibited, this 
  274. function grows the queue, puts the first-in item on the queue, and returns 
  275.  
  276.  TRUE . 
  277. Otherwise, this function returns 
  278.  
  279.  FALSE . 
  280. If there are no elements in the 
  281. queue, an 
  282.  \f3\f3Error\f1\f1 
  283. exception is raised.
  284. .TP
  285.  Type& unput ();
  286. Removes and returns a reference to the last-in item on the queue.
  287. .TP
  288.  inline Type& value ();
  289. Returns a reference to the element at the current position. If the current 
  290. position is invalid, an 
  291.  \f3\f3Error\f1\f1 
  292. exception is raised.
  293. .SH Friend Functions
  294. .TP
  295. \f3friend ostream& operator<< (ostream& \f2os\f3, const Queue<Type>& q\f3);\f1
  296. Overloads the output operator for a reference to a \f3Queue<Type>\f1 object to 
  297. provide a formatted output capability.
  298. .TP
  299. \f3inline friend ostream& operator<< (ostream& \f2os\f3, const Queue<Type>* q\f3);\f1
  300. Overloads the output operator for a pointer to a \f3Queue<Type>\f1 object to provide 
  301. a \p
  302. formatted output capability.
  303. .SH COPYRIGHT
  304.  
  305. Copyright (C) 1991 Texas Instruments Incorporated.
  306.  
  307. Permission is granted to any individual or institution to use, copy, modify,
  308. and distribute this software, provided that this complete copyright and
  309. permission notice is maintained, intact, in all copies and supporting
  310. documentation.
  311.  
  312. Texas Instruments Incorporated provides this software "as is" without
  313. express or implied warranty.
  314.  
  315.